lab components / Actions and controls

Starred

A Starred button allows users to easily like, save, or prioritize an item. It often pins the item to the top of a list or collection for quick access.

Examples Properties Guidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Starred } from "@siteimprove/fancylab";

#Examples

Use default starred variant for users to toggle the starred state of an item, and enable starring on most lists to allow customisation.

Composition:

Icon only button: the primary interactive element.
Star Icon: The primary visual element.
Tooltip (Recommended): A brief text label appearing on hover or focus (e.g., "Marked as favorite").

Interaction:

Default (Unstarred): An outlined star icon is used to show the item is not starred.
Hover: A blue round square border and shadow displayed to indicate that is clickable.
Starred: Typically, a filled star icon is used to indicate the item is starred.
Disabled: The icon appears in a visually muted state (e.g., grayed out) with no interaction.

CodeHTML output

const [starred, setStarred] = useState(false);
return (
	<Starred
		isStarred={starred}
		onChange={setStarred}
		aria-label="Pin/unpin whatever this item is"
	/>
);

Disable the starred button when the user cannot star an item (e.g., due to permissions) or in read-only views.

CodeHTML output

const [starred, setStarred] = useState(false);
return (
	<Starred
		isStarred={starred}
		onChange={setStarred}
		aria-label="Pin/unpin whatever this item is"
		disabled
	/>
);

#Properties

CodePropsHTML output

Property	Description	Defined	Value
isStarredRequired	`boolean`If true, the element selected is starred	YesNo	truefalse
onChangeRequired	`function`Executes once starred button has changed	YesNo
aria-labelOptional	`string`Describe what happens if the button is clicked	YesNo
disabledOptional	`boolean`Can the button be clicked	YesNo	truefalse
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo
onBlurOptional	`function`Callback for onBlur event	YesNo

Users need to quickly mark or bookmark items of interest.
The list or collection of items can benefit from personalization.

#Placement

Starred is typically used in the following places:

List Table: Usually positioned at the leading edge of the item. (e.g My policies)
Data table : Usually positioned at the leading edge of the item. (e.g Sites progress)

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Starred to existing components for visual consistency.

#Do not use when

A more specific action is appropriate (e.g., "Prioritise issue in SEO Insights" ).
The star icon might be confused with rating functionality.

#Accessibility

For designers

Use adequate color contrast for all states of the button.
Ensure the touch/click target is large enough.
Provide alternative text for screen readers (e.g., "Star item" or "Unstar item").

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Tooltip/Label Text

Starred: "Starred" (or "Favorited")
Unstarred: "Star" (or "Favorite")